home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / totdoc.arc / CHAPT13.TXT < prev    next >
Text File  |  1991-02-10  |  17KB  |  425 lines
  1.                                                                         Managing
  2.                                                                            Dates
  3.  
  4.  
  5.  
  6.          "The brain is a wonderful organ; it starts the minute you get up in the
  7.          morning and does not stop until you get to the office."
  8.  
  9.                                                                     Robert Frost
  10.  
  11.  
  12.  
  13.  
  14.  
  15.          Date manipulation has always been a problem for computer programmers.
  16.          If only there were ten days in a week, ten weeks in a year, and ten
  17.          years in a century! Date mathematics is just plain clumsy when you
  18.          think of dates in days, months and years. Try computing the date one
  19.          hundred days after February 20, 1956! Not so easy.
  20.          Date mathematics is greatly simplified when you convert dates into
  21.          their Julian form. Over the centuries, many mathematicians have devised
  22.          methods of accurately computing dates. Most modern computer systems
  23.          (including this Toolkit!) use the Julian system. The Julian period was
  24.          devised in 1582 by Joseph Scaliger, and was named after his father
  25.          Julias (not after the Julian calendar). The Julian system assigns each
  26.          day its own unique number. Day 1 began at noon, January 1, 4713 B.C.
  27.          Every day since that time has its own sequential number, and February
  28.          11, 1991 is Julian period 2448299.
  29.  
  30.          The totDATE unit provides a variety of functions for converting dates
  31.          to and from Julian format. To compute the date one hundred days after
  32.          February 20, 1956, you would convert the date to Julian, add one
  33.          hundred to it, and convert it back to a string. This can be achieved
  34.          with the following compound statement using Toolkit functions.
  35.                   FancyDateStr(GregToJul(2,20,1956)+100,true,true);
  36.  
  37.          This uses the function GregToJul to convert Month/Day/Year to a Julian
  38.          period. A hundred is then added to it, and this value is passed to the
  39.          function FancyDateStr, which returns a text string showing the day and
  40.          date represented by the Julian period. In this example, the following
  41.          date would be returned:
  42.                   Wednesday May 30, 1956
  43.  
  44.          The Toolkit supports dates in eight different formats. Using M, D and Y
  45.          to represent months, days and years respectively, the supported formats
  46.          are:
  47.                                   MMDDYY
  48.                                   MMDDYYYY
  49.                                   MMYY
  50.                                   MMYYYY
  51.                                   DDMMYY
  52.  
  53. 13-2                                                                User's Guide
  54. --------------------------------------------------------------------------------
  55.  
  56.                                   DDMMYYYY
  57.                                   YYMMDD
  58.                                   YYYYMMDD
  59.  
  60.          Many of the totDATE functions need to know in which format the date
  61.          strings are, and so the unit includes the enumerated type tDate, which
  62.          (not surprisingly) has the following members: MMDDYY, MMDDYYYY, MMYY,
  63.          MMYYYY, DDMMYY, DDMMYYYY, YYMMDD and YYYYMMDD.
  64.  
  65.  
  66.  
  67.            Note: if you plan to delve into ancient history with your date
  68.            calculations, you need to be aware of some strange facts. For
  69.            example, different countries decided to drop certain days to
  70.            adjust for inaccuracies in the lunar calendar. In 1752, the Brit-
  71.            ish decreed that the day following September 2 would be September
  72.            14. Further back in 1582, Pope Gregory XIII (of Gregorian calendar
  73.            fame!) decreed that October 4 would become October 15. In 1793 the
  74.            French .... well, you get the idea. For a good summary of these
  75.            calendar aberrations, refer to any copy of The World Almanac and
  76.            Book of Facts.
  77.  
  78.  
  79.  
  80. Using DateTOT
  81.          The totDATE unit includes the object DateOBJ, and a global instance of
  82.          this object, DateTOT. This instance is used to control two of the
  83.          default date configurations. The following two methods control these
  84.          defaults:
  85.  
  86.  
  87.          SetLastYearNextCentury(yr:byte);
  88.          When a year is specified with only two digits, the Toolkit has to
  89.          decide to which century the year refers. This method is used to set the
  90.          largest year, which will be interpreted as falling in the next century.
  91.          For example, if this method is passed a value of 50, then the two digit
  92.          year 50 will be assumed to be 2050, and the two digit year 51 will be
  93.          assumed to be 1951. By default, this year is set to 20.
  94.  
  95.  
  96.          SetSeparator(Sep:char);
  97.          When dates are displayed in their numeric form, a character is used to
  98.          separate the days from the months from the years, e.g. 12-01-1990. This
  99.          default is used to control which character will be used as the separa-
  100.          tor. By default, the character is a slash, i.e. '/'.
  101.  
  102.  
  103.          The following two function methods return the current settings:
  104.  
  105.  
  106.  
  107. Managing Dates                                                              13-3
  108. --------------------------------------------------------------------------------
  109.  
  110.          GetLastYearNextCentury: byte;
  111.          GetSeparator: char;
  112.  
  113.  
  114.          Another purpose of the DateOBJ object is to control how the days of the
  115.          week and months are spelled. This feature is provided for international
  116.          users who want to use a different language. The following DateOBJ meth-
  117.          ods are supported:
  118.  
  119.  
  120.          SetMonths(M1,M2,M3,M4,M5,M6,M7,M8,M9,M10,M11,M12: StrShort);
  121.          This method defines how the months will be spelled. The method is
  122.          passed twelve strings representing the months January through December.
  123.  
  124.  
  125.          SetDays(D0,D1,D2,D3,D4,D5,D6:StrShort);
  126.          This method defines how the days will be spelled. The method is passed
  127.          seven strings representing the days Sunday through Saturday.
  128.  
  129.  
  130.          GetMonth(Mth:byte):string;
  131.          This function method returns a string representing a specific month.
  132.          The method is passed a byte parameter, with a value between one and
  133.          twelve, to indicate which month you want returned.
  134.  
  135.  
  136.          GetDay(Day:byte):string;
  137.          This function method returns a string representing a specific day. The
  138.          method is passed a byte parameter, with a value between zero and six,
  139.          to indicate which month you want returned. Day zero represents Sunday.
  140.  
  141.  
  142.  
  143. Date Functions
  144.          Listed below are the functions used to manipulate date numbers and
  145.          strings:
  146.  
  147. GregToJul
  148.          GregToJul(M,D,Y:longint): longint;
  149.  
  150.          Returns the Julian value of a Gregorian date. The function is passed
  151.          three parameters of type byte, shortint, integer, word or longint; the
  152.          first parameter is the month, the second is the day, and the third is
  153.          the four-digit year. For example:
  154.                   MyJul := GregToJul(3,21,1957);
  155.  
  156.          Assigns the value 1741959 to MyJul.
  157.  
  158.  
  159. 13-4                                                                User's Guide
  160. --------------------------------------------------------------------------------
  161.  
  162. JulToGreg
  163.  
  164.          JulToGreg(Jul:longint; var M,D,Y:longint);
  165.          This procedure converts a Julian date to Gregorian. The function is
  166.          passed four parameters; the first is the source Julian date, and the
  167.          remaining three parameters must be variables of type longint. The ini-
  168.          tial values of these three variables are ignored, and they are updated
  169.          with the month, day and year equivalent of the Julian value. For
  170.          example:
  171.  
  172.                   var
  173.                      Day,Mon,Yr: longint;
  174.                   {...}
  175.                   JulToGreg(2447654,Mon,Day,Yr);
  176.          Assigns the values 5, 7 and 1989 to Mon, Day and Yr, respectively.
  177.  
  178.  
  179.  
  180. GregToStr
  181.          GregToStr(M,D,Y:longint; Format:tDate):string;
  182.  
  183.          Returns a string representing the Gregorian date specified. The func-
  184.          tion is passed four parameters; the first three parameters may be of
  185.          type byte, shortint, word, integer or longint, representing the month,
  186.          day and year. The fourth parameter is a member of the enumerated type
  187.          tDate representing the desired string format. For example:
  188.                   DStr := GregToStr(2,11,1991,DDMMYY);
  189.  
  190.          Assigns the value '11/02/91' to DStr.
  191.  
  192.  
  193. JulToStr
  194.  
  195.          JulToStr(Jul:longint;Format:tDate):string;
  196.          Returns a string representing a Julian date. The function is passed two
  197.          parameters; the Julian date, and the date format. For example:
  198.  
  199.                   DStr := JulToStr(2448299,YYYYMMDD);
  200.          Assigns the value '1991/02/11' to DStr.
  201.  
  202. DOWJul
  203.          DOWJul(Jul:longint):byte;
  204.  
  205.          Returns a byte representing the day of the week for a Julian date. The
  206.          function is passed one parameter; the Julian date. Zero represents
  207.          Sunday, and six represents Saturday, all other days falling in between
  208.          these two. For example:
  209.  
  210. Managing Dates                                                              13-5
  211. --------------------------------------------------------------------------------
  212.  
  213.                   TheDay := DOWJul(2448299);
  214.  
  215.          Assigns the value 1 to TheDay, i.e. Monday.
  216.  
  217.  
  218. DOWStr
  219.  
  220.          DOWStr(DStr:string; Format:tDate):byte;
  221.          This function is similar to DOWJul in as much as it returns the day of
  222.          the week for a specified date. In this case, however, the date is
  223.          specified in string form. The function is passed two parameters; the
  224.          date in string form, and the date format. For example:
  225.  
  226.                   TheDay := DOWStr('02/11/91',MMDDYY);
  227.          Assigns the value 1 to TheDay.
  228.  
  229.  
  230.  
  231. Day
  232.          Day(DStr:string; Format:tDate): word;
  233.  
  234.          This function returns the day represented by a date string. The func-
  235.          tion is passed two parameters; the date in string form, and the date
  236.          format. For example:
  237.                   TheDay := Day('05/30/1956',MMDDYYYY);
  238.  
  239.          Assigns the value 30 to TheDay.
  240.  
  241.  
  242. Month
  243.  
  244.          Month(DStr:string; Format:tDate): word;
  245.          This function returns the month represented by a date string. The func-
  246.          tion is passed two parameters; the date in string form, and the date
  247.          format. For example:
  248.  
  249.                   TheMon := Month('30/05/1956',DDMMYYYY);
  250.          Assigns the value 5 to TheMon.
  251.  
  252.  
  253. Year
  254.          Year(DStr:string; Format:tDate): word;
  255.  
  256.          This function returns the year represented by a date string. The func-
  257.          tion is passed two parameters; the date in string form, and the date
  258.          format. For example:
  259.                   TheYr := Year('1956/05/30',YYYYMMDD);
  260.  
  261. 13-6                                                                User's Guide
  262. --------------------------------------------------------------------------------
  263.  
  264.          Assigns the value 1956 to TheYr.
  265.  
  266.  
  267. ValidDate
  268.          ValidDate(M,D,Y:longint):boolean;
  269.  
  270.          This function returns true if the Gregorian date specified is valid,
  271.          i.e. the month is between one and twelve, and the day is valid for the
  272.          specified month. The function is passed three parameters of type byte,
  273.          shortint, word, integer or longint, representing the month, day and
  274.          year, respectively. For example:
  275.                   OK := ValidDate(2,31,1991);
  276.  
  277.          Assigns the value false to OK.
  278.  
  279. ValidDateStr
  280.  
  281.          ValidDateStr(DStr:string;Format:tDate):boolean;
  282.          This function is similar to ValidDate, except that it validates a
  283.          string date. The function is passed two parameters; the date in string
  284.          form, and the date format. For example:
  285.  
  286.                   OK := ValidDateStr('02/28/1991',MMDDYYYY);
  287.          Assigns the value true to OK.
  288.  
  289.  
  290. TodayInJul
  291.          TodayInJul:longint;
  292.  
  293.          This function calls a DOS interrupt, and returns the system's date in
  294.          Julian form. It is passed no parameters. For example:
  295.                   writeln(JulToStr(TodayInJul,DDMMYY));
  296.  
  297.          Writes the value of the system's date in string form.
  298.  
  299.  
  300. StartOfYear
  301.  
  302.          StartOfYear(Jul:longint):longint;
  303.          Returns the Julian date of January 1 of the year in which the passed
  304.          date falls. The function is passed one parameter; the Julian date of
  305.          the year to be returned. For example:
  306.  
  307.                   JanJul := StartOfYear(2448299);
  308.          Assigns the value 2448258, representing the date Jan 1 1991, to JanJul.
  309.  
  310. Managing Dates                                                              13-7
  311. --------------------------------------------------------------------------------
  312.  
  313. EndOfYear
  314.  
  315.          EndOfYear(Jul:longint):longint;
  316.          Returns the Julian date of December 31 of the year in which the passed
  317.          date falls. The function is passed one parameter; the Julian date of
  318.          the year to be returned. For example:
  319.  
  320.                   DecJul := EndOfYear(2448299);
  321.          Assigns the value 2448622, representing the date Dec 31 1991, to Dec-
  322.          Jul.
  323.  
  324.  
  325.  
  326. RelativeDate
  327.          RelativeDate(DStr:string; Format:tDate; Delta:longint):string;
  328.  
  329.          Returns a string representing a date, which is a specified number of
  330.          days before or after a base date. The function is passed three parame-
  331.          ters; the base date in string form, the date format, and the number of
  332.          days from the base date. The last parameter may be positive or
  333.          negative, depending on whether you want a date after or before the base
  334.          date. For example:
  335.                   DatStr := RelativeDate('04/05/91',MMDDYY,-7);
  336.  
  337.          Assigns the value '03/29/91' to DatStr.
  338.  
  339.  
  340. StripDateStr
  341.  
  342.          StripDateStr(DStr:string; Format:tDate):string;
  343.          This function returns a date string with the date separator removed.
  344.          The function is passed two parameters; the date in string form, and the
  345.          date format. For example:
  346.  
  347.                   SlimStr := StripDateStr('02/11/91',MMDDYY);
  348.          Assigns the value '021191' to SlimStr.
  349.  
  350.  
  351.  
  352. FancyDateStr
  353.          FancyDateStr(Jul:longint; Long,day:boolean): string;
  354.  
  355.          This function returns an attractively formatted string date. The func-
  356.          tion is passed three parameters; the Julian date, and two boolean
  357.          parameters to indicate the desired format. The first boolean parameter
  358.          should be set to true if the month and day of week should be spelled
  359.          out in their long form, or false to use the three character abbrevi-
  360.  
  361.  
  362. 13-8                                                                User's Guide
  363. --------------------------------------------------------------------------------
  364.  
  365.          ation. The second boolean parameter should be set to true if the day of
  366.          the week is to be included, or false if it is not required. For
  367.          example:
  368.  
  369.                   FStr := FancyDateStr(2448299,true,true);
  370.          Assigns the value 'Monday February 11, 1991' to FStr.
  371.  
  372.  
  373.  
  374. DateFormat
  375.          DateFormat(Format:tDate):string;
  376.  
  377.          This function is passed a date format, and returns the string represen-
  378.          tation of that format. For example:
  379.                   MyStr := DateFormat(MMDDYYYY);
  380.  
  381.          Assigns the value 'MMDDYYYY' to MyStr.
  382.  
  383.  
  384. Example
  385.  
  386.          Listed below is the demo program DEMDT2.PAS, followed by figure 13.1
  387.          showing an example of the generated output.
  388.          program DemoDateTwo;
  389.          {DEMDT2 - example date statements}
  390.  
  391.          uses DOS,CRT, totDATE;
  392.          var
  393.           M,D,Y:longint;
  394.  
  395.          begin
  396.             ClrScr;
  397.             writeln(TodayInJul);
  398.             writeln(JultoStr(TodayInJul,DDMMYYYY));
  399.             writeln(FancyDateStr(TodayInJul,false,false));
  400.             writeln(FancyDateStr(TodayInJul,true,false));
  401.             writeln(FancyDateStr(TodayInJul,false,true));
  402.             writeln(FancyDateStr(TodayInJul,true,true));
  403.             writeln;
  404.             writeln(RelativeDate('02/20/56',MMDDYY,90));
  405.             writeln;
  406.             writeln(JulToStr(StartOfYear(StrTo-
  407.          Jul('30/06/1990',DDMMYY)),DDMMYY));
  408.             writeln(JulToStr(EndOfYear(StrToJul('30/06/1990',DDMMYY)),DDMMYY));
  409.             writeln;
  410.             writeln(ValidDateStr('02/29/90',MMDDYY));
  411.             writeln(ValidDate(2,29,90));
  412.             writeln(DateFormat(MMDDYY));
  413.          end.
  414.  
  415.  
  416. Managing Dates                                                              13-9
  417. --------------------------------------------------------------------------------
  418.  
  419. Figure 13.1                                                             [SCREEN]
  420. Date
  421. Functions
  422.  
  423.  
  424.  
  425.